//
//  LGSConnectionContext.h
//  LogicSim
//
//  Created by Jeremy Pereira on 20/04/2012.
//  Copyright (c) 2012 __MyCompanyName__. All rights reserved.
//

/*!
 *  @file LGSConnectionContext.h
 *  @brief Contains definitions pertaining to connection contexts
 *  @author Jeremy PEreira
 */

#import <Foundation/Foundation.h>

@class LGSNode;
@class LGSName;

/*!
 *  @brief name to node map for locating nodes in deserialisations.
 *
 *  Instances of this class record all information known so far about a given 
 *  deserialisation.  So for instance, we have a dictionary of all the defined
 *  nodes so that we can add connections later.  The context is structured as a
 *  stack so that when we get to a new module, we can push the current state
 *  and pop it again at the end of the module parsing.
 *
 */
@interface LGSConnectionContext : NSObject

/*!
 *  @brief Find the node for the given name.
 *
 *  @param nameToSearch name for which the node is required.
 *  @return the node for the given name or nil if not found.
 */
-(LGSNode*) nodeForName: (LGSName*) nameToSearch;

/*!
 *  @brief Add a new node to the context.
 *
 *  The name must be unique within a given context for the current scope.  
 *
 *  @param nodeToAdd The node to add to the context.
 *  @param error If non null the object pointed to will be set to an error if 
 *  the node being added already exists.  
 *  @return true if the node was successfully added.
 */
-(bool) addNode: (LGSNode*) nodeToAdd 
          error: (NSError* __autoreleasing *) error;

/*!
 *  @brief Saves the current state of the connection context so we can go back
 *  to it later.
 */
-(void) push;

/*!
 *  @brief Restores a previously saved state of the context.
 */
-(void) pop;

@end
